<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-type" content="text/html; charset=iso-8859-1">
<title>StAX API - The Java EE 5 Tutorial</title>
<meta name="robots" content="index,follow">
<meta name="robots" content="index,follow">
<meta name="date" content="2008-10-01">
<link rel="stylesheet" type="text/css" href="css/default.css">
<link rel="stylesheet" type="text/css" href="css/ipg.css">
<link rel="stylesheet" type="text/css" href="css/j5eetutorial.css">
</head>

<body>

<table border="0" cellpadding="5" cellspacing="0" width="100%">
<tbody>
   <tr valign="top">
      <td><p class="toc level1"><a href="docinfo.html">Document Information</a></p>
<p class="toc level1 tocsp"><a href="gexaf.html">Preface</a></p>
<p class="toc level1 tocsp"><a href="gfirp.html">Part&nbsp;I&nbsp;Introduction</a></p>
<p class="toc level2"><a href="bnaaw.html">1.&nbsp;&nbsp;Overview</a></p>
<p class="toc level2"><a href="gfiud.html">2.&nbsp;&nbsp;Using the Tutorial Examples</a></p>
<p class="toc level1 tocsp"><a href="bnadp.html">Part&nbsp;II&nbsp;The Web Tier</a></p>
<p class="toc level2"><a href="bnadr.html">3.&nbsp;&nbsp;Getting Started with Web Applications</a></p>
<p class="toc level2"><a href="bnafd.html">4.&nbsp;&nbsp;Java Servlet Technology</a></p>
<p class="toc level2"><a href="bnagx.html">5.&nbsp;&nbsp;JavaServer Pages Technology</a></p>
<p class="toc level2"><a href="bnajo.html">6.&nbsp;&nbsp;JavaServer Pages Documents</a></p>
<p class="toc level2"><a href="bnakc.html">7.&nbsp;&nbsp;JavaServer Pages Standard Tag Library</a></p>
<p class="toc level2"><a href="bnalj.html">8.&nbsp;&nbsp;Custom Tags in JSP Pages</a></p>
<p class="toc level2"><a href="bnaon.html">9.&nbsp;&nbsp;Scripting in JSP Pages</a></p>
<p class="toc level2"><a href="bnaph.html">10.&nbsp;&nbsp;JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="bnaqz.html">11.&nbsp;&nbsp;Using JavaServer Faces Technology in JSP Pages</a></p>
<p class="toc level2"><a href="bnatx.html">12.&nbsp;&nbsp;Developing with JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="bnavg.html">13.&nbsp;&nbsp;Creating Custom UI Components</a></p>
<p class="toc level2"><a href="bnawo.html">14.&nbsp;&nbsp;Configuring JavaServer Faces Applications</a></p>
<p class="toc level2"><a href="bnaxu.html">15.&nbsp;&nbsp;Internationalizing and Localizing Web Applications</a></p>
<p class="toc level1 tocsp"><a href="bnayk.html">Part&nbsp;III&nbsp;Web Services</a></p>
<p class="toc level2"><a href="bnayl.html">16.&nbsp;&nbsp;Building Web Services with JAX-WS</a></p>
<p class="toc level2"><a href="bnazf.html">17.&nbsp;&nbsp;Binding between XML Schema and Java Classes</a></p>
<p class="toc level2"><a href="bnbdv.html">18.&nbsp;&nbsp;Streaming API for XML</a></p>
<p class="toc level3"><a href="bnbdw.html">Why StAX?</a></p>
<p class="toc level4"><a href="bnbdw.html#bnbdx">Streaming versus DOM</a></p>
<p class="toc level4"><a href="bnbdw.html#bnbdy">Pull Parsing versus Push Parsing</a></p>
<p class="toc level4"><a href="bnbdw.html#bnbdz">StAX Use Cases</a></p>
<p class="toc level4"><a href="bnbdw.html#bnbea">Comparing StAX to Other JAXP APIs</a></p>
<div class="onpage">
<p class="toc level3 tocsp"><a href="">StAX API</a></p>
<p class="toc level4"><a href="#bnbed">Cursor API</a></p>
<p class="toc level4"><a href="#bnbee">Iterator API</a></p>
<p class="toc level5"><a href="#bnbef">Iterator Event Types</a></p>
<p class="toc level5"><a href="#bnbeh">Example of Event Mapping</a></p>
<p class="toc level4 tocsp"><a href="#bnbej">Choosing between Cursor and Iterator APIs</a></p>
<p class="toc level5"><a href="#bnbek">Development Goals</a></p>
<p class="toc level5"><a href="#bnbel">Comparing Cursor and Iterator APIs</a></p>
</div>
<p class="toc level3 tocsp"><a href="bnbem.html">Using StAX</a></p>
<p class="toc level4"><a href="bnbem.html#bnben">StAX Factory Classes</a></p>
<p class="toc level5"><a href="bnbem.html#bnbeo"><tt>XMLInputFactory</tt> Class</a></p>
<p class="toc level5"><a href="bnbem.html#bnbeq"><tt>XMLOutputFactory</tt> Class</a></p>
<p class="toc level5"><a href="bnbem.html#bnber"><tt>XMLEventFactory</tt> Class</a></p>
<p class="toc level4 tocsp"><a href="bnbem.html#bnbes">Resources, Namespaces, and Errors</a></p>
<p class="toc level5"><a href="bnbem.html#bnbet">Resource Resolution</a></p>
<p class="toc level5"><a href="bnbem.html#bnbeu">Attributes and Namespaces</a></p>
<p class="toc level5"><a href="bnbem.html#bnbev">Error Reporting and Exception Handling</a></p>
<p class="toc level4 tocsp"><a href="bnbem.html#bnbew">Reading XML Streams</a></p>
<p class="toc level5"><a href="bnbem.html#bnbex">Using <tt>XMLStreamReader</tt></a></p>
<p class="toc level5"><a href="bnbem.html#bnbfb">Using <tt>XMLEventReader</tt></a></p>
<p class="toc level4 tocsp"><a href="bnbem.html#bnbfe">Writing XML Streams</a></p>
<p class="toc level5"><a href="bnbem.html#bnbff">Using <tt>XMLStreamWriter</tt></a></p>
<p class="toc level5"><a href="bnbem.html#bnbfg">Using <tt>XMLEventWriter</tt></a></p>
<p class="toc level3 tocsp"><a href="bnbfi.html">Sun's Streaming XML Parser Implementation</a></p>
<p class="toc level4"><a href="bnbfi.html#bnbfj">Reporting CDATA Events</a></p>
<p class="toc level4"><a href="bnbfi.html#bnbfk">Streaming XML Parser Factories Implementation</a></p>
<p class="toc level3 tocsp"><a href="bnbfl.html">Example Code</a></p>
<p class="toc level4"><a href="bnbfl.html#bnbfm">Example Code Organization</a></p>
<p class="toc level4"><a href="bnbfl.html#bnbfn">Example XML Document</a></p>
<p class="toc level4"><a href="bnbfl.html#bnbfo">Cursor Example</a></p>
<p class="toc level5"><a href="bnbfl.html#bnbfp">Stepping through Events</a></p>
<p class="toc level5"><a href="bnbfl.html#bnbfq">Returning String Representations</a></p>
<p class="toc level5"><a href="bnbfl.html#bnbfr">Building and Running the Cursor Example Using NetBeans IDE</a></p>
<p class="toc level5"><a href="bnbfl.html#bnbfs">Building and Running the Cursor Example Using Ant</a></p>
<p class="toc level4 tocsp"><a href="bnbfl.html#bnbft">Cursor-to-Event Example</a></p>
<p class="toc level5"><a href="bnbfl.html#bnbfu">Instantiating an <tt>XMLEventAllocator</tt></a></p>
<p class="toc level5"><a href="bnbfl.html#bnbfv">Creating an Event Iterator</a></p>
<p class="toc level5"><a href="bnbfl.html#bnbfw">Creating the Allocator Method</a></p>
<p class="toc level5"><a href="bnbfl.html#bnbfx">Building and Running the Cursor-to-Event Example Using NetBeans IDE</a></p>
<p class="toc level5"><a href="bnbfl.html#bnbfy">Building and Running the Cursor-to-Event Example Using Ant</a></p>
<p class="toc level4 tocsp"><a href="bnbfl.html#bnbfz">Event Example</a></p>
<p class="toc level5"><a href="bnbfl.html#bnbga">Creating an Input Factory</a></p>
<p class="toc level5"><a href="bnbfl.html#bnbgb">Creating an Event Reader</a></p>
<p class="toc level5"><a href="bnbfl.html#bnbgc">Creating an Event Iterator</a></p>
<p class="toc level5"><a href="bnbfl.html#bnbgd">Getting the Event Stream</a></p>
<p class="toc level5"><a href="bnbfl.html#bnbge">Returning the Output</a></p>
<p class="toc level5"><a href="bnbfl.html#bnbgf">Building and Running the Event Example Using NetBeans IDE</a></p>
<p class="toc level5"><a href="bnbfl.html#bnbgg">Building and Running the Event Example Using Ant</a></p>
<p class="toc level4 tocsp"><a href="bnbfl.html#bnbgh">Filter Example</a></p>
<p class="toc level5"><a href="bnbfl.html#bnbgi">Implementing the <tt>StreamFilter</tt> Class</a></p>
<p class="toc level5"><a href="bnbfl.html#bnbgj">Creating an Input Factory</a></p>
<p class="toc level5"><a href="bnbfl.html#bnbgk">Creating the Filter</a></p>
<p class="toc level5"><a href="bnbfl.html#bnbgl">Capturing the Event Stream</a></p>
<p class="toc level5"><a href="bnbfl.html#bnbgm">Filtering the Stream</a></p>
<p class="toc level5"><a href="bnbfl.html#bnbgn">Returning the Output</a></p>
<p class="toc level5"><a href="bnbfl.html#bnbgo">Building and Running the Filter Example Using NetBeans IDE</a></p>
<p class="toc level5"><a href="bnbfl.html#bnbgp">Building and Running the Filter Example Using Ant</a></p>
<p class="toc level4 tocsp"><a href="bnbfl.html#bnbgq">Read-and-Write Example</a></p>
<p class="toc level5"><a href="bnbfl.html#bnbgr">Creating an Event Producer/Consumer</a></p>
<p class="toc level5"><a href="bnbfl.html#bnbgs">Creating an Iterator</a></p>
<p class="toc level5"><a href="bnbfl.html#bnbgt">Creating a Writer</a></p>
<p class="toc level5"><a href="bnbfl.html#bnbgu">Returning the Output</a></p>
<p class="toc level5"><a href="bnbfl.html#bnbgv">Building and Running the Read-and-Write Example Using NetBeans IDE</a></p>
<p class="toc level5"><a href="bnbfl.html#bnbgw">Building and Running the Read-and-Write Example Using Ant</a></p>
<p class="toc level4 tocsp"><a href="bnbfl.html#bnbgx">Writer Example</a></p>
<p class="toc level5"><a href="bnbfl.html#bnbgy">Creating the Output Factory</a></p>
<p class="toc level5"><a href="bnbfl.html#bnbgz">Creating a Stream Writer</a></p>
<p class="toc level5"><a href="bnbfl.html#bnbha">Writing the Stream</a></p>
<p class="toc level5"><a href="bnbfl.html#bnbhb">Returning the Output</a></p>
<p class="toc level5"><a href="bnbfl.html#bnbhc">Building and Running the Writer Example Using NetBeans IDE</a></p>
<p class="toc level5"><a href="bnbfl.html#bnbhd">Building and Running the Writer Example Using Ant</a></p>
<p class="toc level3 tocsp"><a href="bnbhe.html">Further Information about StAX</a></p>
<p class="toc level2 tocsp"><a href="bnbhf.html">19.&nbsp;&nbsp;SOAP with Attachments API for Java</a></p>
<p class="toc level1 tocsp"><a href="bnblr.html">Part&nbsp;IV&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="bnbls.html">20.&nbsp;&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="bnbnb.html">21.&nbsp;&nbsp;Getting Started with Enterprise Beans</a></p>
<p class="toc level2"><a href="bnboc.html">22.&nbsp;&nbsp;Session Bean Examples</a></p>
<p class="toc level2"><a href="bnbpk.html">23.&nbsp;&nbsp;A Message-Driven Bean Example</a></p>
<p class="toc level1 tocsp"><a href="bnbpy.html">Part&nbsp;V&nbsp;Persistence</a></p>
<p class="toc level2"><a href="bnbpz.html">24.&nbsp;&nbsp;Introduction to the Java Persistence API</a></p>
<p class="toc level2"><a href="bnbrl.html">25.&nbsp;&nbsp;Persistence in the Web Tier</a></p>
<p class="toc level2"><a href="bnbrs.html">26.&nbsp;&nbsp;Persistence in the EJB Tier</a></p>
<p class="toc level2"><a href="bnbtg.html">27.&nbsp;&nbsp;The Java Persistence Query Language</a></p>
<p class="toc level1 tocsp"><a href="bnbwi.html">Part&nbsp;VI&nbsp;Services</a></p>
<p class="toc level2"><a href="bnbwj.html">28.&nbsp;&nbsp;Introduction to Security in the Java EE Platform</a></p>
<p class="toc level2"><a href="bnbyk.html">29.&nbsp;&nbsp;Securing Java EE Applications</a></p>
<p class="toc level2"><a href="bncas.html">30.&nbsp;&nbsp;Securing Web Applications</a></p>
<p class="toc level2"><a href="bncdq.html">31.&nbsp;&nbsp;The Java Message Service API</a></p>
<p class="toc level2"><a href="bncgv.html">32.&nbsp;&nbsp;Java EE Examples Using the JMS API</a></p>
<p class="toc level2"><a href="bncih.html">33.&nbsp;&nbsp;Transactions</a></p>
<p class="toc level2"><a href="bncjh.html">34.&nbsp;&nbsp;Resource Connections</a></p>
<p class="toc level2"><a href="bncjx.html">35.&nbsp;&nbsp;Connector Architecture</a></p>
<p class="toc level1 tocsp"><a href="bnckn.html">Part&nbsp;VII&nbsp;Case Studies</a></p>
<p class="toc level2"><a href="bncko.html">36.&nbsp;&nbsp;The Coffee Break Application</a></p>
<p class="toc level2"><a href="bnclz.html">37.&nbsp;&nbsp;The Duke's Bank Application</a></p>
<p class="toc level1 tocsp"><a href="gexbq.html">Part&nbsp;VIII&nbsp;Appendixes</a></p>
<p class="toc level2"><a href="bncno.html">A.&nbsp;&nbsp;Java Encoding Schemes</a></p>
<p class="toc level2"><a href="bncnq.html">B.&nbsp;&nbsp;Preparation for Java EE Certification Exams</a></p>
<p class="toc level2"><a href="bncnt.html">C.&nbsp;&nbsp;About the Authors</a></p>
<p class="toc level1 tocsp"><a href="idx-1.html">Index</a></p>
</td>
      <td width="10px">&nbsp;</td>
      <td width="705px">
         <div class="header">
             <div class="header-links-top">
                 <a href="http://java.sun.com">java.sun.com</a> |
                 <a href="http://docs.sun.com/">docs.sun.com</a><br>
             </div> 
             <img src="graphics/tutorialBanner.gif" width="704" height="120" alt="The Java&trade; EE 5 Tutorial"/>
             <div class="header-links">
	         <a href="index.html">Home</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/information/download.html">Download</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/JavaEETutorial.pdf">PDF</a> |
                 <a href="http://java.sun.com/javaee/5/docs/api/index.html">API</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/information/faq.html">FAQ</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/information/search.html">Search</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/information/sendusmail.html">Feedback</a> |
                 <a href="http://java.sun.com/javaee/5/docs/tutorial/information/history.html">History</a>
             </div>
             <div class="navigation">
                 <a href="bnbdw.html"><img style="padding-right: 3px" src="graphics/leftButton.gif" border="0"></a>
                 <a href="sjsaseej2eet.html"><img style="padding-right: 3px" src="graphics/upButton.gif" border="0"></a>
                 <a href="bnbem.html"><img style="padding-left: 3px" src="graphics/rightButton.gif" border="0"></a>
             </div>
         </div>

	 <div class="maincontent">      	 
             

<a name="bnbec"></a><h3>StAX API</h3>
<a name="indexterm-1837"></a><p>The StAX API exposes methods for iterative, event-based processing of XML documents. XML
documents are treated as a filtered series of events, and infoset states can
be stored in a procedural fashion. Moreover, unlike SAX, the StAX API is
bidirectional, enabling both reading and writing of XML documents.</p><p>The StAX API is really two distinct API sets: a <b>cursor</b> API and
an <b>iterator</b> API. These two API sets explained in greater detail later in
this chapter, but their main features are briefly described below.</p>

<a name="bnbed"></a><h4>Cursor API</h4>
<a name="indexterm-1838"></a><a name="indexterm-1839"></a><p>As the name implies, the StAX <b>cursor</b> API represents a cursor with which
you can walk an XML document from beginning to end. This cursor can
point to one thing at a time, and always moves forward, never
backward, usually one infoset element at a time.</p><p>The two main cursor interfaces are <tt>XMLStreamReader</tt> and <tt>XMLStreamWriter</tt>. <tt>XMLStreamReader</tt> includes accessor methods
for all possible information retrievable from the XML Information model, including document encoding,
element names, attributes, namespaces, text nodes, start tags, comments, processing instructions, document boundaries, and
so forth; for example:</p><pre>public interface XMLStreamReader {
    public int next() throws XMLStreamException;
    public boolean hasNext() throws XMLStreamException;
    public String getText();
    public String getLocalName();
    public String getNamespaceURI();
    // ... other methods not shown
}</pre><p>You can call methods on <tt>XMLStreamReader</tt>, such as <tt>getText</tt> and <tt>getName</tt>, to
get data at the current cursor location. <tt>XMLStreamWriter</tt> provides methods that correspond to <tt>StartElement</tt>
and <tt>EndElement</tt> event types; for example:</p><pre>public interface XMLStreamWriter {
    public void writeStartElement(String localName) 
        throws XMLStreamException;
    public void writeEndElement() 
        throws XMLStreamException;
    public void writeCharacters(String text) 
        throws XMLStreamException;
// ... other methods not shown
}</pre><p>The cursor API mirrors SAX in many ways. For example, methods are
available for directly accessing string and character information, and integer indexes can be used
to access attribute and namespace information. As with SAX, the cursor API methods
return XML information as strings, which minimizes object allocation requirements.</p>

<a name="bnbee"></a><h4>Iterator API</h4>
<a name="indexterm-1840"></a><a name="indexterm-1841"></a><p>The StAX <b>iterator</b> API represents an XML document stream as a set of
discrete event objects. These events are pulled by the application and provided by
the parser in the order in which they are read in the source
XML document.</p><p>The base iterator interface is called <tt>XMLEvent</tt>, and there are subinterfaces for each
event type listed in <a href="#bnbeg">Table&nbsp;18-2</a>. The primary parser interface for reading iterator
events is <tt>XMLEventReader</tt>, and the primary interface for writing iterator events is
<tt>XMLEventWriter</tt>. The <tt>XMLEventReader</tt> interface contains five methods, the most important of which is
<tt>nextEvent</tt>, which returns the next event in an XML stream. <tt>XMLEventReader</tt> implements <tt>java.util.Iterator</tt>,
which means that returns from <tt>XMLEventReader</tt> can be cached or passed into
routines that can work with the standard Java Iterator; for example:</p><pre>public interface XMLEventReader extends Iterator {
    public XMLEvent nextEvent() throws XMLStreamException;
    public boolean hasNext();
    public XMLEvent peek() throws XMLStreamException;
    ...
}</pre><p>Similarly, on the output side of the iterator API, you have:</p><pre>public interface XMLEventWriter {
    public void flush() throws XMLStreamException;
    public void close() throws XMLStreamException;
    public void add(XMLEvent e) throws XMLStreamException;
    public void add(Attribute attribute) throws XMLStreamException;
    ...
}</pre>

<a name="bnbef"></a><h5>Iterator Event Types</h5>
<a name="indexterm-1842"></a><p><a href="#bnbeg">Table&nbsp;18-2</a> lists the <tt>XMLEvent</tt> types defined in the event iterator API.</p><a name="bnbeg"></a><h6>Table&nbsp;18-2 <tt>XMLEvent</tt> Types</h6><table><col width="25%"><col width="74%"><tr><th align="left" valign="top" scope="column"><p>Event Type</p></th>
<th align="left" valign="top" scope="column"><p>Description</p></th>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>StartDocument</tt></p></td>
<td align="left" valign="top" scope="row"><p>Reports
the beginning of a set of XML events, including encoding, XML version, and
standalone properties.</p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>StartElement</tt></p></td>
<td align="left" valign="top" scope="row"><p>Reports the start of an element, including any attributes and namespace declarations;
also provides access to the prefix, namespace URI, and local name of the
start tag.</p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>EndElement</tt></p></td>
<td align="left" valign="top" scope="row"><p>Reports the end tag of an element. Namespaces that have gone
out of scope can be recalled here if they have been explicitly set
on their corresponding <tt>StartElement</tt>.</p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>Characters</tt></p></td>
<td align="left" valign="top" scope="row"><p>Corresponds to XML <tt>CData</tt> sections and <tt>CharacterData</tt> entities. Note
that ignorable white space and significant white space are also reported as <tt>Character</tt>
events.</p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>EntityReference</tt></p></td>
<td align="left" valign="top" scope="row"><p>Character entities can be reported as discrete events, which an application developer can
then choose to resolve or pass through unresolved. By default, entities are resolved.
Alternatively, if you do not want to report the entity as an event,
replacement text can be substituted and reported as <tt>Characters</tt>.</p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>ProcessingInstruction</tt></p></td>
<td align="left" valign="top" scope="row"><p>Reports the target and
data for an underlying processing instruction.</p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>Comment</tt></p></td>
<td align="left" valign="top" scope="row"><p>Returns the text of a comment.</p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>EndDocument</tt></p></td>
<td align="left" valign="top" scope="row"><p>Reports the
end of a set of XML events.</p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>DTD</tt></p></td>
<td align="left" valign="top" scope="row"><p>Reports as <tt>java.lang.String</tt> information about the DTD,
if any, associated with the stream, and provides a method for returning custom
objects found in the DTD.</p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>Attribute</tt></p></td>
<td align="left" valign="top" scope="row"><p>Attributes are generally reported as part of a
<tt>StartElement</tt> event. However, there are times when it is desirable to return an
attribute as a standalone <tt>Attribute</tt> event; for example, when a namespace is returned as
the result of an <tt>XQuery</tt> or <tt>XPath</tt> expression.</p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p><tt>Namespace</tt></p></td>
<td align="left" valign="top" scope="row"><p>As with attributes, namespaces are
usually reported as part of a <tt>StartElement</tt>, but there are times when
it is desirable to report a namespace as a discrete <tt>Namespace</tt> event.</p></td>
</tr>
</table><p>Note that the <tt>DTD</tt>, <tt>EntityDeclaration</tt>, <tt>EntityReference</tt>, <tt>NotationDeclaration</tt>, and <tt>ProcessingInstruction</tt> events are only
created if the document being processed contains a DTD.</p>

<a name="bnbeh"></a><h5>Example of Event Mapping</h5>
<a name="indexterm-1843"></a><a name="indexterm-1844"></a><p>As an example of how the event iterator API maps an XML
stream, consider the following XML document:</p><pre>&lt;?xml version="1.0"?>
&lt;BookCatalogue xmlns="http://www.publishing.org">
    &lt;Book>
        &lt;Title>Yogasana Vijnana: the Science of Yoga&lt;/Title>
        &lt;ISBN>81-40-34319-4&lt;/ISBN>
        &lt;Cost currency="INR">11.50&lt;/Cost>
    &lt;/Book>
&lt;/BookCatalogue></pre><p>This document would be parsed into eighteen primary and secondary events, as shown
in <a href="#bnbei">Table&nbsp;18-3</a>. Note that secondary events, shown in curly braces (<tt>{}</tt>), are typically accessed
from a primary event rather than directly.</p><a name="bnbei"></a><h6>Table&nbsp;18-3 Example of Iterator API Event Mapping</h6><table><col width="6%"><col width="72%"><col width="21%"><tr><th align="left" valign="top" scope="column"><p>#</p></th>
<th align="left" valign="top" scope="column"><p>Element/Attribute</p></th>
<th align="left" valign="top" scope="column"><p>Event</p></th>
</tr>
<tr><td align="left" valign="top" scope="row"><p>1</p></td>
<td align="left" valign="top" scope="row"><pre>version="1.0"</pre></td>
<td align="left" valign="top" scope="row"><p><tt>StartDocument</tt></p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p>2</p></td>
<td align="left" valign="top" scope="row"><pre>isCData = false
data = "\n"
IsWhiteSpace = true</pre></td>
<td align="left" valign="top" scope="row"><p><tt>Characters</tt></p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p>3</p></td>
<td align="left" valign="top" scope="row"><pre>qname = BookCatalogue:http://www.publishing.org
attributes = null
namespaces = {BookCatalogue" -> http://www.publishing.org"}</pre></td>
<td align="left" valign="top" scope="row"><p><tt>StartElement</tt></p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p>4</p></td>
<td align="left" valign="top" scope="row"><pre>qname = Book
attributes = null
namespaces = null</pre></td>
<td align="left" valign="top" scope="row"><p><tt>StartElement</tt></p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p>5</p></td>
<td align="left" valign="top" scope="row"><pre>qname = Title
attributes = null
namespaces = null</pre></td>
<td align="left" valign="top" scope="row"><p><tt>StartElement</tt></p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p>6</p></td>
<td align="left" valign="top" scope="row"><pre>isCData = false
data = "Yogasana Vijnana: the Science of Yoga\n\t"
IsWhiteSpace = false</pre></td>
<td align="left" valign="top" scope="row"><p><tt>Characters</tt></p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p>7</p></td>
<td align="left" valign="top" scope="row"><pre>qname = Title
namespaces = null</pre></td>
<td align="left" valign="top" scope="row"><p><tt>EndElement</tt></p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p>8</p></td>
<td align="left" valign="top" scope="row"><pre>qname = ISBN
attributes = null
namespaces = null</pre></td>
<td align="left" valign="top" scope="row"><p><tt>StartElement</tt></p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p>9</p></td>
<td align="left" valign="top" scope="row"><pre>isCData = false
data = "81-40-34319-4\n\t"
IsWhiteSpace = false</pre></td>
<td align="left" valign="top" scope="row"><p><tt>Characters</tt></p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p>10</p></td>
<td align="left" valign="top" scope="row"><pre>qname = ISBN
namespaces = null</pre></td>
<td align="left" valign="top" scope="row"><p><tt>EndElement</tt></p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p>11</p></td>
<td align="left" valign="top" scope="row"><pre>qname = Cost
attributes = {"currency" -> INR}
namespaces = null</pre></td>
<td align="left" valign="top" scope="row"><p><tt>StartElement</tt></p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p>12</p></td>
<td align="left" valign="top" scope="row"><pre>isCData = false
data = "11.50\n\t"
IsWhiteSpace = false</pre></td>
<td align="left" valign="top" scope="row"><p><tt>Characters</tt></p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p>13</p></td>
<td align="left" valign="top" scope="row"><pre>qname = Cost
namespaces = null</pre></td>
<td align="left" valign="top" scope="row"><p><tt>EndElement</tt></p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p>14</p></td>
<td align="left" valign="top" scope="row"><pre>isCData = false
data = "\n"
IsWhiteSpace = true</pre></td>
<td align="left" valign="top" scope="row"><p><tt>Characters</tt></p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p>15</p></td>
<td align="left" valign="top" scope="row"><pre>qname = Book
namespaces = null</pre></td>
<td align="left" valign="top" scope="row"><p><tt>EndElement</tt></p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p>16</p></td>
<td align="left" valign="top" scope="row"><pre>isCData = false
data = "\n"
IsWhiteSpace = true</pre></td>
<td align="left" valign="top" scope="row"><p><tt>Characters</tt></p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p>17</p></td>
<td align="left" valign="top" scope="row"><pre>qname = BookCatalogue:http://www.publishing.org
namespaces = {BookCatalogue" -> http://www.publishing.org"}</pre></td>
<td align="left" valign="top" scope="row"><p><tt>EndElement</tt></p></td>
</tr>
<tr><td align="left" valign="top" scope="row"><p>18</p></td>
<td align="left" valign="top" scope="row"></td>
<td align="left" valign="top" scope="row"><p><tt>EndDocument</tt></p></td>
</tr>
</table><p>There are several important things to note in this example:</p>
<ul><li><p>The events are created in the order in which the corresponding XML elements are encountered in the document, including nesting of elements, opening and closing of elements, attribute order, document start and document end, and so forth.</p></li>
<li><p>As with proper XML syntax, all container elements have corresponding start and end events; for example, every <tt>StartElement</tt> has a corresponding <tt>EndElement</tt>, even for empty elements.</p></li>
<li><p><tt>Attribute</tt> events are treated as secondary events, and are accessed from their corresponding <tt>StartElement</tt> event.</p></li>
<li><p>Similar to <tt>Attribute</tt> events, <tt>Namespace</tt> events are treated as secondary, but appear twice and are accessible twice in the event stream, first from their corresponding <tt>StartElement</tt> and then from their corresponding <tt>EndElement</tt>.</p></li>
<li><p><tt>Character</tt> events are specified for all elements, even if those elements have no character data. Similarly, <tt>Character</tt> events can be split across events.</p></li>
<li><p>The StAX parser maintains a namespace stack, which holds information about all XML namespaces defined for the current element and its ancestors. The namespace stack, which is exposed through the <tt>javax.xml.namespace.NamespaceContext</tt> interface, can be accessed by namespace prefix or URI.</p></li></ul>


<a name="bnbej"></a><h4>Choosing between Cursor and Iterator APIs</h4>
<a name="indexterm-1845"></a><p>It is reasonable to ask at this point, &ldquo;What API should I
choose? Should I create instances of <tt>XMLStreamReader</tt> or <tt>XMLEventReader</tt>? Why are there two
kinds of APIs anyway?&rdquo;</p>

<a name="bnbek"></a><h5>Development Goals</h5>
<p>The authors of the StAX specification targeted three types of developers:</p>
<ul><li><p><b>Library and infrastructure developers</b>: Need highly efficient, low-level APIs with minimal extensibility requirements.</p></li>
<li><p><b>J2ME developers</b>: Need small, simple, pull-parsing libraries, and have minimal extensibility needs.</p></li>
<li><p><b>Java EE and Java SE developers</b>: Need clean, efficient pull-parsing libraries, plus need the flexibility to both read and write XML streams, create new event types, and extend XML document elements and attributes.</p></li></ul>
<p>Given these wide-ranging development categories, the StAX authors felt it was more useful
to define two small, efficient APIs rather than overloading one larger and necessarily
more complex API.</p>

<a name="bnbel"></a><h5>Comparing Cursor and Iterator APIs</h5>
<p>Before choosing between the cursor and iterator APIs, you should note a few
things that you can do with the iterator API that you cannot
do with cursor API:</p>
<ul><li><p>Objects created from the <tt>XMLEvent</tt> subclasses are immutable, and can be used in arrays, lists, and maps, and can be passed through your applications even after the parser has moved on to subsequent events.</p></li>
<li><p>You can create subtypes of <tt>XMLEvent</tt> that are either completely new information items or extensions of existing items but with additional methods.</p></li>
<li><p>You can add and remove events from an XML event stream in much simpler ways than with the cursor API.</p></li></ul>
<p>Similarly, keep some general recommendations in mind when making your choice:</p>
<ul><li><p>If you are programming for a particularly memory-constrained environment, like J2ME, you can make smaller, more efficient code with the cursor API.</p></li>
<li><p>If performance is your highest priority (for example, when creating low-level libraries or infrastructure), the cursor API is more efficient.</p></li>
<li><p>If you want to create XML processing pipelines, use the iterator API.</p></li>
<li><p>If you want to modify the event stream, use the iterator API.</p></li>
<li><p>If you want your application to be able to handle pluggable processing of the event stream, use the iterator API.</p></li>
<li><p>In general, if you do not have a strong preference one way or the other, using the iterator API is recommended because it is more flexible and extensible, thereby &ldquo;future-proofing&rdquo; your applications.</p></li></ul>

         </div>
         <div class="navigation">
             <a href="bnbdw.html"><img style="padding-right: 3px" src="graphics/leftButton.gif" border="0"></a>
             <a href="sjsaseej2eet.html"><img style="padding-right: 3px" src="graphics/upButton.gif" border="0"></a>
             <a href="bnbem.html"><img style="padding-left: 3px" src="graphics/rightButton.gif" border="0"></a>
         </div>

         <div class="copyright">
      	    <p>The material in The Java&trade; EE 5 Tutorial is <a href='docinfo.html'>copyright</a>-protected and may not be published in other works without express written permission from Sun Microsystems.</p>
      	 </div>

      </td>
   </tr>
</tbody>
</table>
</body>
</html>

